{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Transport efficiency and the models for tortuosity factor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "PyBaMM models utilize a ratio that we refer to as \"transport efficiency\" $\\mathcal{B}$ which can be applied to transport co-efficients such as the diffusivity in the electrolyte that relates the effective transport property through a porous media comprised of a conducting and non-conducting phase to that of the transport through the bulk of the conducting phase:\n",
    "$$\n",
    "\\mathcal{B} = \\frac{X_{eff}}{X_0} = \\frac{\\epsilon}{\\tau},\n",
    "$$\n",
    "\n",
    "Where $\\epsilon$ is the volume fraction of the conducting phase, the porosity of the electrode for diffusion within the electrolyte, and $\\tau$ is the tortuosity factor. A measure of the effect of the increased pathlength that transported species traverse due to the presence of obstacles.\n",
    "\n",
    "The tortuosity and tortuosity factor are often used interchangably but this can lead to confusion. Tortusosity is a purely geometric concept relating the length of a winding capillary pathway through a medium with the length of that medium, whereas tortuosity factor relates the the ratio of the transport property which may also depend on other factors such as anisotropic obstacles, boundary conditions of flow and also other physical phenomena such as the average pore size which could induce Knudsen effects. \n",
    "\n",
    "Many studies have been devoted to understanding relations between $\\tau$ and $\\epsilon$ including those summarized by [Shen & Chen](https://www.sciencedirect.com/science/article/abs/pii/S0009250907003144). By far the most common is the Bruggeman relation which is explored more recently by [Tjaden et al.](http://dx.doi.org/10.1016/j.coche.2016.02.006) in the context of materials commonly found in batteries and fuel cells."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A recent study by [Usseglio-Viretta et al.](https://iopscience.iop.org/article/10.1149/2.0731814jes) found that Bruggeman and similar relations can significantly underpredict the tortuosity factors. If used at all these relations are often more suitable for the cathode where particles are more spherical but should be used with caution for the anode. A more recent trend is to use numerical methods to calculate tortuosity factors directly from image data gathered for electrodes in which case a straight-forward relation with porosity may not exist and is not necessary if factors can be directly supplied."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The remainder of the notebook demonstrates how to use the different options for transport efficiency and supply your own tortuosity factor"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "import pybamm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['Bruggeman', 'ordered packing', 'hyperbola of revolution', 'overlapping spheres', 'tortuosity factor', 'random overlapping cylinders', 'heterogeneous catalyst', 'cation-exchange membrane']\n"
     ]
    }
   ],
   "source": [
    "sols = []\n",
    "te_opts = pybamm.BatteryModelOptions({}).possible_options[\"transport efficiency\"]\n",
    "parameter_values = pybamm.ParameterValues(\"Marquis2019\")\n",
    "print(te_opts)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Negative electrode porosity\t0.3\n",
      "Positive electrode porosity\t0.3\n",
      "Separator porosity\t1.0\n"
     ]
    }
   ],
   "source": [
    "parameter_values.search(\"porosity\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Negative electrode Bruggeman coefficient (electrode)\t1.5\n",
      "Negative electrode Bruggeman coefficient (electrolyte)\t1.5\n",
      "Positive electrode Bruggeman coefficient (electrode)\t1.5\n",
      "Positive electrode Bruggeman coefficient (electrolyte)\t1.5\n",
      "Separator Bruggeman coefficient (electrolyte)\t1.5\n"
     ]
    }
   ],
   "source": [
    "parameter_values.search(\"Bruggeman\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add tortuosity factors that replicate the Bruggeman values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "parameter_values.update(\n",
    "    {\n",
    "        \"Negative electrode tortuosity factor (electrolyte)\": 0.3 ** (-0.5),\n",
    "        \"Positive electrode tortuosity factor (electrolyte)\": 0.3 ** (-0.5),\n",
    "        \"Negative electrode tortuosity factor (electrode)\": 0.7 ** (-0.5),\n",
    "        \"Positive electrode tortuosity factor (electrode)\": 0.7 ** (-0.5),\n",
    "        \"Separator tortuosity factor (electrolyte)\": 1.0,\n",
    "    },\n",
    "    check_already_exists=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "N.B the differences in the exponent constants used to modify the porosity and solid volume fraction. The existing Bruggeman model applies the exponent directly to the porosity $\\mathcal{B}=\\epsilon^{b}=\\epsilon^{3/2}$, the tortuosity factor model applies the tortuosity factor with includes the relation on porosity in this case $\\mathcal{B}=\\epsilon / \\tau = \\epsilon / \\epsilon^{-1/2} = \\epsilon^{3/2}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "for t_label in te_opts:\n",
    "    model = pybamm.lithium_ion.DFN(\n",
    "        options={\"transport efficiency\": t_label}\n",
    "    )  # Doyle-Fuller-Newman model\n",
    "    sim = pybamm.Simulation(model, parameter_values=parameter_values)\n",
    "    sols.append(sim.solve([0, 3600]))  # solve for 1 hour"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "2a0d1356fdaf495c8898429e27e30478",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.plotting.quick_plot.QuickPlot at 0x105f6705f90>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pybamm.dynamic_plot(sols, labels=te_opts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Bruggeman and tortuosity factor results should be identical"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.allclose(sols[0][\"Terminal voltage [V]\"].data, sols[4][\"Terminal voltage [V]\"].data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now increase the tortuosity factors. N.B this will need to be calculated for specific electrodes with given porosity. Changing porosity in the model will not update the tortuosity factor unless a function is supplied for the parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "parameter_values.update(\n",
    "    {\n",
    "        \"Negative electrode tortuosity factor (electrolyte)\": 4.0,\n",
    "        \"Positive electrode tortuosity factor (electrolyte)\": 4.0,\n",
    "        \"Negative electrode tortuosity factor (electrode)\": 3.0,\n",
    "        \"Positive electrode tortuosity factor (electrode)\": 3.0,\n",
    "        \"Separator tortuosity factor (electrolyte)\": 1.5,\n",
    "    },\n",
    "    check_already_exists=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "model = pybamm.lithium_ion.DFN(\n",
    "    options={\"transport efficiency\": \"tortuosity factor\"}\n",
    ")  # Doyle-Fuller-Newman model\n",
    "sim = pybamm.Simulation(model, parameter_values=parameter_values)\n",
    "sols.append(sim.solve([0, 3600]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "5292e8b8c6884c199cf5023cf42ea3ac",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<pybamm.plotting.quick_plot.QuickPlot at 0x105f8f85fd0>"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pybamm.dynamic_plot(sols, labels=[*te_opts, \"higher tortuosity factor\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The higher tortuosity leads to greater overpotential in the electrolyte and lower terminal voltage"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1] KA Akanni, JW Evans, and IS Abramson. Effective transport coefficients in heterogeneous media. Chemical Engineering Science, 42(8):1945–1954, 1987.\n",
      "[2] Joel A. E. Andersson, Joris Gillis, Greg Horn, James B. Rawlings, and Moritz Diehl. CasADi – A software framework for nonlinear optimization and optimal control. Mathematical Programming Computation, 11(1):1–36, 2019. doi:10.1007/s12532-018-0139-4.\n",
      "[3] JW Beeckman. Mathematical description of heterogeneous materials. Chemical engineering science, 45(8):2603–2610, 1990.\n",
      "[4] Von DAG Bruggeman. Berechnung verschiedener physikalischer konstanten von heterogenen substanzen. i. dielektrizitätskonstanten und leitfähigkeiten der mischkörper aus isotropen substanzen. Annalen der physik, 416(7):636–664, 1935.\n",
      "[5] Marc Doyle, Thomas F. Fuller, and John Newman. Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell. Journal of the Electrochemical society, 140(6):1526–1533, 1993. doi:10.1149/1.2221597.\n",
      "[6] Charles R. Harris, K. Jarrod Millman, Stéfan J. van der Walt, Ralf Gommers, Pauli Virtanen, David Cournapeau, Eric Wieser, Julian Taylor, Sebastian Berg, Nathaniel J. Smith, and others. Array programming with NumPy. Nature, 585(7825):357–362, 2020. doi:10.1038/s41586-020-2649-2.\n",
      "[7] JS Mackie and P Meares. The diffusion of electrolytes in a cation-exchange resin membrane i. theoretical. Proceedings of the Royal Society of London. Series A. Mathematical and Physical Sciences, 232(1191):498–509, 1955.\n",
      "[8] Scott G. Marquis, Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society, 166(15):A3693–A3706, 2019. doi:10.1149/2.0341915jes.\n",
      "[9] EE Petersen. Diffusion in a pore of varying cross section. AIChE Journal, 4(3):343–345, 1958.\n",
      "[10] Lihua Shen and Zhangxin Chen. Critical review of the impact of tortuosity on diffusion. Chemical Engineering Science, 62(14):3748–3755, 2007.\n",
      "[11] Valentin Sulzer, Scott G. Marquis, Robert Timms, Martin Robinson, and S. Jon Chapman. Python Battery Mathematical Modelling (PyBaMM). Journal of Open Research Software, 9(1):14, 2021. doi:10.5334/jors.309.\n",
      "[12] Manolis M Tomadakis and Stratis V Sotirchos. Transport properties of random arrays of freely overlapping cylinders with various orientation distributions. The Journal of chemical physics, 98(1):616–626, 1993.\n",
      "[13] Harold L Weissberg. Effective diffusion coefficient in porous media. Journal of Applied Physics, 34(9):2636–2639, 1963.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "pybamm.print_citations()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
